Skip to content

docs: default_device() can be None #961

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: default_device() can be None #961

wants to merge 1 commit into from

Conversation

ev-br
Copy link
Member

@ev-br ev-br commented Jun 23, 2025

closes gh-923.

Per discussion in the community meeting, https://hackmd.io/zn5bvdZTQIeJmb3RW1B-8g#Meeting-minutes-15-May-2025 and the resolution of #923 (comment), spell out explicitly that None is an allowed return value of the default_device.

@lucascolley lucascolley changed the title DOC: default_device can be None docs: default_device() can be None Jun 23, 2025
@jakevdp
Copy link

jakevdp commented Jun 23, 2025

A comment here: the wording implies that None has a special meaning – but my understanding is that the spec makes no requirements of what objects libraries use to represent devices, and so adding special meaning to None is not really necessary.

In the motivating example, JAX doesn't use None to mean that "the default device is not predictable due to library specific device placement rules", it uses None to represent the concept of uncommitted placement on the default device.

@ev-br
Copy link
Member Author

ev-br commented Jun 23, 2025 •
edited
Loading

JAX ... uses None to represent the concept of uncommitted placement on the default device.

This is one example of thea library specific device placement rule, I'd say :-).

That said, there's nothing special about the proposed wording here. Anything which says "None is allowed" is strictly better than what's in main, so if you've PR with a better wording, I'm happy to close this PR in favor of yours.

betatim
betatim reviewed Jun 25, 2025
View reviewed changes
src/array_api_stubs/_draft/info.py
Comment on lines +83 to +85
an object corresponding to the default device or ``None``.
A conforming array library may return ``None`` if the default device is not
predictable due to library specific device placement rules.
Copy link
Member

@betatim betatim Jun 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
an object corresponding to the default device or ``None``.
A conforming array library may return ``None`` if the default device is not
predictable due to library specific device placement rules.
an object (including ``None``) corresponding to the default device or ``None``.

I'd formulate it like this - because if we were to be super pedantic we wouldn't need to mention None at all as it is an object. I find this a nice way to say "all objects, including None (which you might have forgotten about), are allowed.

I don't think the docstring of the return value needs to hypothesis about when a library might want to use which value. If we want to get into that I think the Notes or Examples section would be better suited

@kgryte kgryte added this to the v2025 milestone Jun 25, 2025
@kgryte kgryte added API change Changes to existing functions or objects in the API. topic: Device Handling Device handling. labels Jun 25, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@betatim betatim betatim left review comments

Assignees
No one assigned
Labels
API change Changes to existing functions or objects in the API. topic: Device Handling Device handling.
Projects
None yet
Milestone
v2025
Development

Successfully merging this pull request may close these issues.

clarify if __array_namespace_info().default_device() can be None
4 participants
@ev-br @jakevdp @betatim @kgryte